/*
 * 
 *  This file is part of Sourceprojects.org Lycia Copyright 2010 noctarius
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 * 
 */
package org.sourceprojects.lycia;

import org.sourceprojects.lycia.exceptions.LyciaParsingException;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.Node;

/**
 * The interface for internally used delegates to call the registered tag parser
 * methods. At the moment there are two delivered implementations: A reflective
 * and a Bytecode delegate.
 * 
 * @author noctarius
 * @since 1.9.1
 * 
 * @param <B>
 *            Type of ContextObject to use
 */
public interface Delegate<B> {

	/**
	 * Calls the internal representation of the parsing method
	 * 
	 * @param element
	 *            Actual {@link Document} element
	 * @param localName
	 *            The localName of the element
	 * @param parent
	 *            A possibly available parent element
	 * @param parserContext
	 *            The actual {@link ParserContext} implementation
	 * @param definitionBuilder
	 *            The actual {@link DefinitionBuilder} implementation
	 * @throws LyciaParsingException
	 *             Every internal Exception is wrapped intp
	 *             XmlParserParsingException
	 */
	void invokeParse(Element element, String localName, QualifiedName parent,
			ParserContext<B> parserContext, DefinitionBuilder definitionBuilder)
			throws LyciaParsingException;

	/**
	 * Calls the internal representation of the transforming method
	 * 
	 * @param element
	 *            Actual {@link Document} element
	 * @param localName
	 *            The localName of the element
	 * @param parent
	 *            A possibly available parent element
	 * @param parserContext
	 *            The actual {@link ParserContext} implementation
	 * @param definitionBuilder
	 *            The actual {@link DefinitionBuilder} implementation
	 * @return The transformed node or null to remove element from transformed
	 *         {@link Document}
	 * @throws LyciaParsingException
	 *             Every internal Exception is wrapped intp
	 *             XmlParserParsingException
	 */
	Node invokeTransform(Element element, String localName,
			QualifiedName parent, ParserContext<B> parserContext,
			DefinitionBuilder definitionBuilder) throws LyciaParsingException;
}
